1. Field of the Invention
The present invention relates generally to systems and methods for providing file documentation, and more particularly to systems and methods for adding comments to computer program code. Still more particularly, the present invention is a system and method for documenting and displaying computer program code.
2. Description of the Background Art
Computer programs often exhibit complex internal functional organizations and information flows. A person attempting to understand a program's internal behavior may therefore face a difficult task. Unfortunately, the program code, which is the most complete description of the program, is not by itself the best description of a program to a person. A person often has difficulties understanding how various blocks of program code are interrelated, or how a particular programming language construct is being used in a given situation. Many hours may be required to decipher and understand interrelated blocks of program code, which are often scattered among different files. In object-oriented programming languages, subtle interactions between various object class hierarchies often affect program control flow in intricate ways. Thus, deciphering object-oriented program code can be particularly difficult.
Program code documentation plays a vital role in making programs easier to understand. Programming languages generally provide a basic documenting capability by which programmers can insert textual comments into program code. The textual comments are typically placed "in-line" immediately preceding or following a possible point of confusion. A given programming language construct such as a variable, function, or class may appear many times in a program. Commenting on each occurrence of a particular variable, function, or class can be a very tedious task. Thus, programmers typically provide only sparse comments or do not fully comment every instance of a given programming language construct. A few programming languages, most notably common LISP, provide a means for automatically associating a textual comment with each occurrence of a function or variable that has been defined globally. However, no similar commenting capability is provided for locally defined functions or variables.
As comments become more detailed or more numerous, they visually interfere with a program code organization or format that the programmer uses to identify program code blocks. Commenting can therefore make computer program code more difficult to decipher or even unreadable. As a result, comments are often made more brief than needed, and only summarize important information. In addition, because comments are typically quite localized, they convey little information related to overall program organization. Thus, even when comments are present, an undesirable amount of time is required to understand and interrelate blocks of program code. Moreover, the commenting capabilities currently provided by programming languages do not allow programmers to portray non-textual information that is useful for program code understanding, such as a flowchart. Therefore, commenting capabilities provided by existing programming languages are generally inadequate for providing in-depth descriptions of program code functionality and organization.
Some program development environments use hypercomments as an approach to make program code more understandable. In such program development environments, a textual comment can be defined once for a particular string of characters representing a programming language construct. For each occurrence of the particular string of characters in the program, the user can select the string, and the program development environment locates the corresponding comment through string matching. As an example, if a user defines a comment for a function named "foo" in a program, the program development environment will look up the text corresponding to the string "foo" whenever the user selects the string "foo" within the program.
In a computer program, semantically different programming language constructs often share an identical name. Thus, a given function, a global variable, and a local variable may each share the same name. For example, a local variable named "foo" may exist within the function named "foo" described above. Identically-named programming language constructs should be commented differently when they are semantically different. Unfortunately, program development environments that provide hypercommenting functionality cannot determine whether programming language constructs having the same name are semantically related. Program development environments that rely upon hypercommenting therefore do not provide an adequate solution to the problem of making program code easier to understand.
What is needed is a means for making program code understandable that does not visually interfere with program code organization or readability, that enables a programmer to convey descriptive information in multiple ways, and that can determine whether identically-named programming language constructs are related.